Description

Adds Management API endpoints to sort the children of a node by a chosen system field (name, create date, update date) and direction — an "auto-arrange" that persists the result as the children's sort order. Scoped to Documents and Media.

New endpoints

All take a JSON body and return 200 OK on success, 400 Bad Request if the field is unrecognised, or 404 Not Found if the parent doesn't exist.

Request body:

// Document
{ "field": "name" | "createDate" | "updateDate",
  "direction": "Ascending" | "Descending",   // required
  "culture": "en-US" }                       // optional

// Media (no culture)
{ "field": "createDate", "direction": "Descending" }

Handling variants

For variant handling I've looked to match the existing manual drag-drop "sort children" UX, which displays the variant name but the node-level create date.

As such the provided culture only affects sorting by name. When provided, variant children are ordered by their name in that culture; invariant children, or variant children with no name for that culture, fall back to the invariant name.

Create/update dates are node-level, not culture-specific.

Other notes

• Ordering is performed in the database, the same way the collection/list view orders its items.
• Limited to system fields that live in a database table (name / create date / update date). Property-data fields I've considered as out of scope, since children need not share a type, so may not have the same properties.
• Sorting a node with no children is a successful no-op (200).
• Unrecognised field values are rejected at model binding (the field is a typed enum), and defensively mapped to 400 at the service layer.
• Culture is not validated, and falls back to invariant if not found.
• Persistence is optimised for potentially large child sets and, by default, differs from the manual drag-drop sort — see Sorting large numbers of children below.

Sorting large numbers of children

The manual drag-and-drop sort is naturally self-limiting: an editor has to load and reorder every child in the client before submitting, so it's impractical to trigger on huge sets. This endpoint is different — it can reorder a node's entire set of children from a single button click, regardless of how many there are, and a field sort typically moves most of them. Reusing the standard per-item sort would mean loading every child into memory and issuing (in the worst case) one UPDATE and one save/sort notification — and therefore one webhook — per child.

To keep this cheap and safe by default, a field sort is persisted differently from the manual sort:

• The new order is computed in the database (reusing the same ordering as the list view) and applied with a single set-based UPDATE in the repository (IContentRepository.UpdateSortOrder, batched only to stay within the SQL Server parameter limit). The editing service collects the ordered child ids by paging — it does not hold every child in memory.
• A single branch cache refresh and a single audit entry are emitted instead of per-item ones. The branch refresh is sufficient because the published cache reads sort order live from umbracoNode.
• Consequently, no per-item save/sort notifications (and therefore no webhooks) are fired for a field sort by default.

For the small number of cases that depend on those per-item notifications/webhooks, the previous behaviour can be restored with the Umbraco:CMS:Content:SortChildrenByFieldFiresNotifications setting (default false). When enabled, the field sort goes through the standard per-item sort path instead, accepting the additional performance cost on nodes with many children. The combined audit entry and single branch refresh are used in both cases — only the per-item notifications differ.

Testing

Automated

Integration tests have been added at the service level to verify the ordering functionality.

Controller authorization tests for all four endpoints are also added.

Manual

Prerequisites: run the site and sign in to the backoffice — this authenticates the Swagger UI via the auth cookie. (Any other client must send the backoffice credentials, i.e. credentials: include.)

1. Open Swagger UI at https://localhost:44339/umbraco/swagger/index.html (adjust the port to your launch settings) and select the Management API definition. The new operations are under the Document and Media tags, ending in /sort-children.

2. Set up content to sort. Create a parent document with a handful of children whose names are deliberately out of order (e.g. "Banana", "Apple", "Cherry") and, ideally, different create/update dates. For variant testing, use a culture-varying document type with two languages and give the children different names per culture.

3. Sort the children of a node — PUT /umbraco/management/api/v1/document/{id}/sort-children, where {id} is the parent's key:

   { "field": "name", "direction": "Ascending" }

   Expect 200 OK, then refresh the tree / list view under the parent and confirm the new order.

4. Sort root-level items — PUT /umbraco/management/api/v1/document/root/sort-children (no id), same body.

5. Variant check (documents only). Repeat step 3 with a culture:

   { "field": "name", "direction": "Ascending", "culture": "da-DK" }

   Confirm the order reflects the Danish names. Call again with "culture": "en-US" and confirm the order changes to the English names.

6. Dates. Call with "field": "createDate" or "updateDate" and confirm ordering by the node-level dates (a culture has no effect on these).

7. Media. Repeat against /media/{id}/sort-children and /media/root/sort-children. The media body has no culture.

8. Error cases.

   • Unknown parent: PUT /document/{random-guid}/sort-children → 404 Not Found.
   • Unrecognised field: body { "field": "bogus", "direction": "Ascending" } → 400 Bad Request.

Documentation

Need to document the new SortChildrenByFieldFiresNotifications setting.

Related

References #19703.